# 배포 설명서 (DEPLOYMENT.md)

로고삽입기 배포 버전의 설정 및 배포 구조를 설명합니다.

---

## 📦 배포 폴더 구조

```
로고삽입기/
├── 로고삽입기.exe              (실행 프로그램)
├── _internal/                 (PyInstaller 라이브러리)
├── config.json               (설정 파일 - 외부 유지)
├── assets/                   (로고 폴더 - 외부 유지)
│   ├── logo_left.png         (왼쪽 로고)
│   └── logo_right.png        (오른쪽 로고)
├── README.md                 (사용자 가이드)
└── DEPLOYMENT.md             (이 파일)
```

### 🔑 중요: 외부 파일 유지

- **config.json**: EXE와 같은 폴더에 위치 (버전 업그레이드 후에도 설정 유지)
- **assets/**: EXE와 같은 폴더 내 (사용자가 로고 파일 직접 교체 가능)

---

## 🛠️ EXE 빌드 방법

### 필수 도구

```
Python 3.8 이상
PyInstaller: pip install pyinstaller
Pillow: pip install Pillow
```

### 빌드 단계

**1단계: 소스 코드 준비**

개발 폴더 d:\AI-WORKS\03-로고삽입기에서:

```bash
# 개발 테스트 (선택사항)
python -m src.main
```

**2단계: EXE 빌드**

```bash
build_exe.bat
```

또는 수동:

```bash
pyinstaller ^
  --onefile ^
  --console ^
  --name 로고삽입기 ^
  --distpath "dist" ^
  src/main.py
```

**3단계: 배포 폴더 구성**

빌드 완료 후:

```
dist/
└── 로고삽입기.exe
```

이를 배포 폴더로 이동:

```
로고삽입기/
├── 로고삽입기.exe              (dist/ 에서 복사)
├── _internal/                 (dist/ 에서 복사, 자동 생성됨)
├── config.json               (d:\AI-WORKS\03-로고삽입기\ 에서 복사)
├── assets/                   (d:\AI-WORKS\03-로고삽입기\assets\ 에서 복사)
│   ├── logo_left.png
│   └── logo_right.png
├── README.md                 (d:\AI-WORKS\03-로고삽입기\README.md 에서 복사)
└── DEPLOYMENT.md             (이 파일)
```

### ⚠️ PyInstaller 주의사항

- **--add-data 미사용**: config.json과 assets는 EXE 내부에 포함하지 않음
- **외부 파일 유지**: 사용자가 설정과 로고를 직접 수정할 수 있어야 함
- **상대 경로 사용**: EXE 옆의 config.json과 assets 폴더 자동 감지

---

## 🔧 배포 후 설정 수정

### config.json 편집

배포 폴더의 `config.json`을 메모장으로 열어 수정할 수 있습니다.

**전화번호 변경 예시:**

```json
{
  ...
  "phone_text": {
    "enabled": true,
    "text": "새 전화번호를 여기에 입력",  ← 이 부분 수정
    ...
  }
}
```

### 로고 파일 교체

1. `assets/` 폴더를 엽니다
2. `logo_left.png` 또는 `logo_right.png`를 새 로고 파일로 교체
3. 파일명은 정확히 `logo_left.png`, `logo_right.png`로 유지
4. 프로그램 다시 실행

---

## 🎯 배포 모드 동작 흐름

### 사용자 관점

```
1. 로고삽입기.exe 실행
     ↓
2. 폴더 선택 다이얼로그 표시
     ↓
3. 사용자가 처리할 폴더 선택
     ↓
4. 자동 처리 시작
     ↓
5. 결과 폴더 생성
     폴더명_로고삽입완료_20260703_120530
     ↓
6. 처리 완료 메시지 표시
     ↓
7. 프로그램 종료
```

### 결과 폴더 생성 규칙

- **위치**: 선택한 폴더와 같은 상위 폴더 내
- **폴더명**: `{원본폴더명}_로고삽입완료_{YYYYMMDD}_{HHMMSS}`
- **예시**:
  - 선택: `C:\Users\사용자\사진\여름휴가`
  - 결과: `C:\Users\사용자\사진\여름휴가_로고삽입완료_20260703_120530`

### 로그 위치

- **개발 모드**: `d:\AI-WORKS\03-로고삽입기\logs\`
- **배포 모드**: 결과 폴더 내 `logs\` (예: `여름휴가_로고삽입완료_20260703_120530\logs\`)

---

## 📝 설정 파일 상세 가이드

### logos 섹션 - 로고 설정

```json
"logos": [
  {
    "id": 1,
    "name": "회사 로고 (왼쪽)",
    "file": "assets/logo_left.png",    ← 로고 파일 경로
    "type": "image",
    "position": "top_left",             ← top_left, top_right, bottom_left, bottom_right
    "margin": 20,                       ← 모서리 거리 (픽셀)
    "width_percent": {
      "landscape": 12,                  ← 가로 사진에서 로고 너비 (%)
      "portrait": 30,                   ← 세로 사진에서 로고 너비 (%)
      "square": 20                      ← 정사각형 사진에서 로고 너비 (%)
    },
    "opacity": 1.0                      ← 투명도 (0.0 ~ 1.0)
  }
]
```

### phone_text 섹션 - 전화번호 텍스트 설정

```json
"phone_text": {
  "enabled": true,                      ← 활성화 여부
  "text": "042-826-0326",               ← 표시할 전화번호
  "position": "bottom_right",           ← 위치
  "margin": {
    "landscape": 40,                    ← 가로 사진 여백
    "portrait": 70,                     ← 세로 사진 여백
    "square": 50                        ← 정사각형 사진 여백
  },
  "font_size_percent": {
    "landscape": 9.0,                   ← 가로 사진 텍스트 크기 (%)
    "portrait": 5.2,                    ← 세로 사진 텍스트 크기 (%)
    "square": 4.2                       ← 정사각형 사진 텍스트 크기 (%)
  },
  "color": "#FFFFFF",                   ← 텍스트 색상 (16진 RGB)
  "stroke_color": "#000000",            ← 테두리 색상
  "stroke_width": 4,                    ← 테두리 두께
  "opacity": 1.0,                       ← 투명도
  "background": {
    "enabled": true,                    ← 배경 박스 활성화
    "color": "#000000",                 ← 배경 색상
    "opacity": 0.45,                    ← 배경 투명도
    "padding": 12                       ← 텍스트와 배경 간격
  }
}
```

---

## 🧪 배포 후 테스트

### 기본 테스트

1. **EXE 실행**: `로고삽입기.exe` 더블클릭
2. **폴더 선택**: 테스트 사진 폴더 선택
3. **처리 확인**: 결과 폴더 생성 확인
4. **로고 확인**: 결과 이미지에 로고 삽입 확인
5. **로그 확인**: 결과 폴더\logs\ 내 로그 파일 확인

### 고급 테스트

**설정 변경 반영 확인:**
1. config.json 수정
2. EXE 재실행
3. 변경사항 적용 확인

**로고 교체 확인:**
1. assets/logo_left.png 교체
2. EXE 재실행
3. 새 로고 적용 확인

---

## 🆘 배포 후 문제 해결

### 오류: "설정 파일을 로드할 수 없습니다"

**원인**: config.json이 EXE 옆에 없음

**해결**:
1. 배포 폴더 구조 확인
2. config.json이 로고삽입기.exe와 같은 폴더에 있는지 확인
3. 파일명이 정확히 "config.json"인지 확인 (대문자 등 주의)

### 오류: "로고 파일 없음"

**원인**: assets/logo_left.png 또는 logo_right.png 파일 없음

**해결**:
1. `assets/` 폴더가 로고삽입기.exe 옆에 있는지 확인
2. logo_left.png, logo_right.png 파일 확인
3. PNG 형식인지 확인 (JPG 등 다른 형식 불가)

### 오류: "폴더 선택하지 않았습니다"

**원인**: 사용자가 폴더 선택 다이얼로그에서 취소 클릭

**해결**: 정상 동작 - 프로그램이 종료되므로 다시 실행하여 폴더 선택

---

## 📞 기술 지원

배포 후 문제 발생 시:

1. 로그 파일 확인 (`결과_폴더/logs/` 내)
2. README.md의 "문제 해결" 섹션 참고
3. config.json이 올바른 JSON 형식인지 검증
4. 관리자에게 로그 파일 제공하며 문의

---

## 📌 체크리스트 - 배포 전 확인

배포 폴더 완성 후 다음을 확인하세요:

- [ ] `로고삽입기.exe` 존재 및 실행 가능
- [ ] `_internal/` 폴더 존재 (PyInstaller 자동 생성)
- [ ] `config.json` 존재 및 유효한 JSON 형식
- [ ] `assets/logo_left.png` 존재 (PNG 형식)
- [ ] `assets/logo_right.png` 존재 (PNG 형식)
- [ ] `README.md` 존재 (사용자용)
- [ ] `DEPLOYMENT.md` 존재 (기술용)
- [ ] EXE 실행 테스트 완료
- [ ] 폴더 선택 다이얼로그 정상 작동 확인
- [ ] 테스트 사진 처리 완료 확인
- [ ] 결과 폴더 생성 확인
- [ ] 로그 파일 생성 확인 (결과 폴더 내)

---

**버전:** 1.0.0  
**최종 수정:** 2026-07-03  
**배포 담당:** AI-WORKS 팀
